<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: Profile      (Energy Profiler)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__group__energy__profiler.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">API Reference</a>  </div>
  <div class="headertitle">
<div class="title">Profile (Energy Profiler)</div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">General Description</h2>
<p>The energy profiler driver is an API for configuring and using the profile hardware block. </p>
<p>The functions and other declarations used in this driver are in cy_profile.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.</p>
<p>The profile block enables measurement of the signal activity of select peripherals and monitor sources during a measurement window. Using these measurements, you can construct a profile of the energy consumed in the device by scaling the individual peripheral activities with appropriate scaling (weight) factors. This gives the application the ability to monitor the energy consumed by the internal resources with minimal CPU overhead and without external monitoring hardware.</p>
<h1><a class="anchor" id="group_profile_details"></a>
Details</h1>
<h2><a class="anchor" id="group_profile_hardware"></a>
Profile Hardware</h2>
<p>The profile hardware consists of a number of profile counters that accept specific triggers for incrementing the count value. This allows the events of the source (such as the number of SCB0 bus accesses or the duration of time the BLE RX radio is active) to be counted during the measurement window. The available monitor sources in the device can be found in the en_ep_mon_sel_t enum in the device configuration file (e.g. psoc62_config.h). These can be sourced to any of the profile counters as triggers. There are two methods of using the monitor sources in a profile counter.</p>
<ul>
<li>Event: The count value is incremented when a pulse event signal is seen by the counter. This type of monitoring is suitable when the monitoring source of interest needs to count the discrete events (such as the number of flash read accesses) happening in the measurement window.</li>
<li>Duration: The count value is incremented at every clock edge while the monitor signal is high. This type of monitoring is suitable when a signal is active for a finite amount of time (such as the time the BLE TX radio is active) and the duration must be expressed as number of clock cycles in the measurement window.</li>
</ul>
<p>Many of the available monitor sources are suitable for event type monitoring. Using a duration type on these signals may not give valuable information. Review the device TRM for more information on the monitor sources and detail on how they should be used.</p>
<h2><a class="anchor" id="group_profile_measurement_types"></a>
Measurement Types</h2>
<p>Depending on the item of interest, energy measurement can be performed by using the following methods.</p>
<ul>
<li>Continuous measurement: A profile counter can be assigned a monitor signal of constant 1 (PROFILE_ONE), which sets the counter to increment at every (assigned) clock cycle. This can be used to give a reference time for the measurement window and also allows the construction of timestamps. For example, a software controlled GPIO can be "timestamped" by reading the counter value (on the fly) before it is toggled. When the measurement window ends, the energy contribution caused by the GPIO toggle can be incorporated into the final calculation.</li>
<li>Event measurement: Monitored events happening in a measurement window can be used to increment a profile counter. This gives the activity numbers, which can then be multiplied by the instantaneous power numbers associated with the source to give the average energy consumption (Energy = Power x time). For example, the energy consumed by an Operating System (OS) task can be estimated by monitoring the processor's active cycle count (E.g. CPUSS_MONITOR_CM4) and the flash read accesses (CPUSS_MONITOR_FLASH). Note that these activity numbers can also be timestamped using the continuous measurement method to differentiate between the different task switches. The activity numbers are then multiplied by the associated processor and flash access power numbers to give the average energy consumed by that task.</li>
<li>Duration measurement: A peripheral event such as the SMIF select signal can be used by a profile counter to measure the time spent on XIP communication through the SPI interface. This activity number can then be multiplied by the power associated with that activity to give the average energy consumed by that block during the measurement window. This type of monitoring should be performed only for signals that are difficult to track in software. For example, a combination of interrupts and timestamps can be used to track the activity of many peripherals in a continuous monitoring model. However tracking the activity of signals such the BLE radio should be done using the duration measurement method.</li>
<li>Low power measurement: The profile counters do not support measurement during chip Deep Sleep, Hibernate, and off states. I.e. the profile counters are meant for active run-time measurements only. To measure the time spent in low power modes (LPM), a real-time clock (RTC) should be used. Take a timestamp before LPM entry and a timestamp upon LPM exit in a continuous measurement model. Then multiply the difference by the appropriate LPM power numbers.</li>
</ul>
<h2><a class="anchor" id="group_profile_usage"></a>
Driver Usage</h2>
<p>At the highest level, the energy profiler must perform the following steps to obtain a measurement:</p>
<ol type="1">
<li>Initialize the profile hardware block.</li>
<li>Initialize the profile interrupt (profile_interrupt_IRQn).</li>
<li>Configure, initialize, and enable the profile counters.</li>
<li>Enable the profile interrupt and start the profiling/measurement window.</li>
<li>Perform run-time reads of the counters (if needed).</li>
<li>Disable the profile interrupt and stop the profiling/measurement window.</li>
<li>Read the counters and gather the results.</li>
<li>Calculate the energy consumption.</li>
</ol>
<p>Refer to the SysInt driver on the details of configuring the profile hardware interrupt.</p>
<p>The profile interrupt triggers when a counter overflow event is detected on any of the enabled profile counters. A sample interrupt service routine <a class="el" href="group__group__profile__functions__interrupt.html#gaf530fa03abe1f90c9788ed4ee1ed140f" title="EP interrupt handler: Increments the overflow member of the counter structure, for each counter that ...">Cy_Profile_ISR()</a> is provided, which can be used to update the internal counter states stored in RAM. Refer to the Configuration Considerations for more information.</p>
<h1><a class="anchor" id="group_profile_configuration"></a>
Configuration Considerations</h1>
<p>Each counter is a 32-bit register that counts either a number of clock cycles, or a number of events. Overflowing the 32-bit register is possible. To address this issue, the driver implements a 32-bit overflow counter. Combined with the 32-bit register, this gives a 64-bit counter for each monitored source.</p>
<p>When an overflow occurs, the profile hardware generates an interrupt. The interrupt is configured using the SysInt driver, where the sample interrupt handler <a class="el" href="group__group__profile__functions__interrupt.html#gaf530fa03abe1f90c9788ed4ee1ed140f" title="EP interrupt handler: Increments the overflow member of the counter structure, for each counter that ...">Cy_Profile_ISR()</a> can be used as the ISR. The ISR increments the overflow counter for each profiling counter and clears the interrupt.</p>
<h1><a class="anchor" id="group_profile_more_information"></a>
More Information</h1>
<p>See the profiler chapter of the device technical reference manual (TRM).</p>
<h1><a class="anchor" id="group_profile_changelog"></a>
Changelog</h1>
<table class="doxtable">
<tr>
<th>Version</th><th>Changes</th><th>Reason for Change </th></tr>
<tr>
<td>1.30 </td><td>Fixed MISRA 2012 violations. </td><td>MISRA 2012 compliance.  </td></tr>
<tr>
<td>1.20.1 </td><td>Minor documentation updates. </td><td>Documentation enhancement.  </td></tr>
<tr>
<td>1.20 </td><td>Updated API function <a class="el" href="group__group__profile__functions__calculation.html#gaf7064fd5a7d413a42fb9d3053cf8f8ea">Cy_Profile_GetSumWeightedCounts()</a>. </td><td>Minor defect fixing: now the function supports the correct number of counters.  </td></tr>
<tr>
<td rowspan="3">1.10 </td><td>Flattened the organization of the driver source code into the single source directory and the single include directory. </td><td>Driver library directory-structure simplification.  </td></tr>
<tr>
<td>Added register access layer. Use register access macros instead of direct register access using dereferenced pointers. </td><td>Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.  </td></tr>
<tr>
<td>Added parameter check asserts. </td><td>Driver defect fix.  </td></tr>
<tr>
<td>1.0 </td><td>Initial version </td><td></td></tr>
</table>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
API Reference</h2></td></tr>
<tr class="memitem:group__group__profile__macros"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__profile__macros.html">Macros</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__profile__functions"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__profile__functions.html">Functions</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__profile__data__structures"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__profile__data__structures.html">Data Structures</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__profile__enums"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__profile__enums.html">Enumerated Types</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
